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HP49 Assembly Language Examples 


This document is aimed at System RPL programmers who wish to learn 
Assembly. We will assume MASD syntax in SysRPL mode on a 49 for the 


documentation of MASD look here: http://www.hpcalc.org/details.php?id=2986 


The following programs are very useful for programming, they are virtually 
indispensable. SysRPL programmers probably have these already. 


ROM version 1.19-6, Other ROM’s may cause problems with the following 
programs 


http://www.hpcalc.org/details.php?id=3240 


For programming itself you should of course have the extable library. 


http://www. epita.fr/~avenar_j|/hp/49.html 


Emacs is the programming environment for the 49, get it! 


http://www.hpcalc.org/details.php?id=3940 


Nosy can be used to look into the code of Rom routines and other programmes, 
which is very educational. 


http://www.hpcalc.org/details.php?id=4323 


It is a good idea to step through some of these programs to see how they work. 
It is the way | learned Assembly. | recommend J azz6.8e 's DB. 


http://www.hpcalc.org/details.php?id=4700 


If you want to know everything about assembly you should read: 
“Introduction to Saturn Assembly Language’ available at 


http://www.hpcalc.org/details.php?id=1695. 


For a description of romroutines you can take a look at the ML part of 
entries.srt But remember it is a 48 document so the addresses will be different 


http://www.hpcalc.org/details.php?id=1782 


Carsten Dominik’s Entry Database also is a great source of romroutine 
descriptions. It contains entries.srt and more. 


http://Zzon.astro.uva.nl/~dominik/hpcalc/entries/ 


For a complete description of the 48 RAM you can study rammap.a 


http://www.hpcalc.org/details.php?id=3231 
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0. Introduction 


Although these examples will not crash your 49, it is probably a good idea to 
backup your memory. Typos are easily made! You can also upload the file 
examples.bz to your 49, it is a selfextracting directory containing all the 
examples. It will save you loads of work typing everything in. 


The last four chapters have a few advanced examples, you might want to 
postpone examining them until you have taken a look at the other examples. 


We will learn to use the registers of the SATURN in due course but it is useful 
that you know them now: 












































Registers Description Communicates with: Width in 
nibbles 

A working register |All, except RSTK, ST, P 16 

B, D working register |C, A 16 

C working register | All 16 

RO...R4 scratch registers |C, A 16 

DO, D1 memory pointer |C, A 5 

DATO, DAT1 memory itself CoA 2°20 

RSTK return stack c 5 

PC program counter |C, A 5 

IN IN register CA 4 

OUT OUT register C,A 8 

P field selector C 1 

mae status bits C 4 

















To read from memory you set DO (or D1) to the correct value and then do 
A=DATO f. f Is a field selector 


The working and scratch registers are 16 nibbles wide and operations can work 
on different fields. 


Field Selection 








P [P-P] 9 ------------------------------------------------ 
WP [0-P] He VAST SST Ad eM 0% Bis TEE 6 bes LAs Be Des As 0 

XS [2-2] 9 ------------------------------------------------ 
X [0-2] |s | |xs|<-B->| 
S. isis] |<---- A ----- > | 
M [3-14] | <-------------- M ---------------- >|<-- x ->| 
B [0-1] | <--------------------- W -------------------- > | 
W [0-15] 

A [0-4] 


We will use the A field very frequently, it is 5 nibbles wide and the A stands for 
Address. As the address space of the SATURN is 5 nibbles. The B register is the 
Byte register, it is particularly useful when you are working with strings. 


Some examples of instructions 


A=CA this speaks for itself; copy the contents of field A of C 
toA 

A=DATO B copy from memory location DO into A(B) 

AR1EX W exchange the contents of A and R1 

LC 123 load C with #123h 

GOSBVL romroutine calls romroutine 

GOSUB subroutine calls subroutine 


The code is set in blue font for better readability. 


1. Basics 


Generally, ML objects are called from RPL (User/Sys) and when they finish they 
need to return to RPL again. This means that certain registers must contain the 
right values. 


D (A) the amount of free mem (in chunks of 5 nibbles) 
D1 points to top of the stack (level 1) 

DO points to the runstream 

B (A) pointer to top of return stack 


It is *MPERATI VE* that you set these correctly before you return to RPL. You 
may crash your calculator if they are wrong. Also the field selector register P 
must be 0. 

EXAMPLE 1.1 From ASM to RPL 


When finishing a ML program you need to set the Program Counter (PC) to the 
next object in the runstream. 


DO contains an address which has the address of the next object in the 
runstream. 


AIDE 

A=DAT0O A % recall next object in runstream 

DO+5 % set DO to "nextnext" object in runstream 

PC=(A) % set the program counter to the address A 
% iS pointing to 

ENDCODE 

@" 


EXAMPLE 1.2 Calling Romroutines 


to call a romroutine there are two commands 
GOSBVL which means GOSuBVeryLong, and 
GOVLNG which stands for GOVeryLoNG. 


Remember that GOVLNG does not set the ReturnStack so when you call a 
routine with GOVLNG your code will not continue after the romroutine. It is 
mainly used for routines that return you to RPL. 


Example 1.1 can also be written as 

"CODE 

GOVLNG Loop 

ENDCODE 

@" 

Loop is a subroutine that does exactly what Example 1.1 does 
We use GOVLNG because you do not need to continue after Loop 


EXAMPLE 1.3 Saving RPL pointers 


The previous examples do not do very much, in fact they do nothing. If we want 
to do more we will probably need to use more registers. But remember? We 
need to set them back to the right values. Fortunately there are romroutines that 
do this for you: SAVPTR saves the RPL pointers and GETPTR recalls them 


"CODE 

GOSBVL SAVPTR % save RPL pointers, use GOSBVL 
% because we want to 
% continue after this 

GOSBVL GETPTR % get the pointers back 

GOVLNG Loop % return to RPL 

ENDCODE 

@" 


There is also a Subroutine that does the last two lines in one; 
romroutine GETPTRLOOP. 


EXAMPLE 1.4 DI SPKEY 

| want to mention here that there is a romroutine which displays the contents of 
all the registers and waits for you to press a key: DISPKEY, you can also call it 
with GOSBVL DBUG.TOUCHE 


"CODE 

GOSBVL SAVPTR % save RPL pointers 

DISPKEY % display the registers 

GOVLNG GETPTRLOOP % get the pointers back and return 
% to RPL 

ENDCODE 

@" 


These programs still do not do anything, but it is important that you understand 
how they work. 


EXAMPLE 1.5 Loading a register with a constant 

Quite often you will need to load a constant into a register. You can do this with 
P, DO, D1 and A and C. The following program shows how, please step through it 
with J azz or insert DISPKEY’S. 


"ODE 
GOSBVL SAVPTR % save RPL pointers 
DO= 12345 % load hex digits 12345 in DO 
DO= 12 % load 12 into the two least 
% significant digits of DO 
% DO now has 12312 


LA 1234567890ABCDEF % fill A with constant 


f=) 


D=0 W % Q is the only constant that will also 
% work with B and D 

C=0 W % clear C to see the next one more 
% Clearly 

P=3 % load the filed selector with 3 

Le ze % load 123 into C but start at digit 
% three, C will now contain 
% 0000000000123000 

P=0 % reset P to 0, or else RPL will crash 

GOVLNG GETPTRLOOP % get the pointers back and return 
% to RPL 

ENDCODE 

@” 


2. The Stack 


Quite often you will need your code to work on an object on the stack. D1 points 
to the first stack level so we can get the address of the object on the stack there. 


EXAMPLE 2.1 Doubling a binary integer 
Let's double the binary integer on the stack. We need to make sure there is an 
integer on the stack, we use SysRpl to put one there 


A Bint (binary integer) is an object with a prologue #02911h and a body of 5 
nibbles: 

BINT 1 = 1192010000 

BINT 12F45 = 1192054F21 


A good way to explore the syntax of objects is the command ->H. 


BINT1 ( put bint on the stack) 
CODE 
A=DAT1A % read address of bint 
Di4+5 % point to next item on stack 
% (basically removing level 1) 
D+1A % free mem has increased by 5 nibbles 
SAVE % MASD syntax for GOSBVL SAVPTR 
DO=A % DO now points to the bint in the 
% memory 
DO+5 % skip the bint prologue 
A=DATOA % read the value of the bint 
A+tAA % double the value 


GOVLNG PUSH#ALOOP % does GETPTR, pushes the value of A(A) 
% to the stack as a bint and then 
% goes to RPL 

ENDCODE 


z 


@" 


There is also a subroutine that gets the address of the object on the stack and 
saves the RPL pointers: "PopASavptr" so we could replace 

"A=DAT1A 

D1+5 

D+1A 

SAVE" 

in example 2.1 with 

"GOSBVL PopASavptr" 


Sometimes you just want the value of the BINT on the stack. POP# gets it for 
you. It puts the value of the bint in A(A) but be sure to have the RPL pointers 


intact, use it before you do GOSBVL SAVPTR! 


Now that we know what binary integers are and how to pop and push them onto 
the stack, we can take a look at dividing and multiplying. MULTBAC multiplies 


A(A) and C(A) and puts the result in B(A) 


EXAMPLE 2.2 Multiplying 


BINT10 ( put two bints on the stack ) 


GOSBVL MULTBAC % multiply A and C, result in B 
A=BA % can’t push B so put it in A 


BINT3 

CODE 

GOSBVL POP# % pop bint 3 

R4=A A % save in R4 
GOSBVL POP# % pop bint 10 to A(A) 
SAVE % save RPL pointers 
C=R4A % Cis 3, Ais still 10 
GOVLNG PUSH#ALOOP % push A to the stack 
ENDCODE 

@" 


To divide two integers we have IntDiv, it divides A(A) by C(A) and puts the result 


in C the remainder will be in A. 


EXAMPLE 2.3 Dividing 


C=R4A % Chas bint 3 and A still has bint 10 


RO=C A % put the values in RO and R1 
R1=A A % because PUSH2# pushes those 


"=: BINT1O. BINT3 

CODE 

GOSBVL POP# 

R4=A A % save bint 3 in R4 
GOSBVL POP# % bint 10 inA 

SAVE % save pointers now 
GOSBVL IntDiv % devide A by C 
GOSBVL GETPTR % get RPL pointers 
GOSBVL PUSH2# % and push RO and Rl 
GOVLNG Loop % return to RPL 
ENDCODE 

@" 


( put two bints on the stack) 
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EXAMPLE 2.4 Editing a string 


We will now make a string which contains "HP49G" 

Because we will get to making objects from scratch in a later stage we will 
assume that there is a 5 character string on level 1 of the stack. 

strings have the following structure: 

prologue, #02A2Ch 

length field, 5 nibbles. It has the size of the string in nibbles, including the size 
of the length field itself but excluding the prologue. For a 5 character string it is 
therefore: 5 nibbles for the length field and 10 nibbles for the 5 characters which 
comes to 15 nibbles. 

body, the characters 


"AAAAA" 


CODE 

GOSBVL PopASavptr % save RPL and get addr of string 

RO=A A % save the addr of the string in RO 

DO=A % point to string prologue 

DO+5 % skip prologue 

DO+5 % skip length 

LC 48 % load C register with #48h which is 
% the character number of "H" 

DATO=C B % write one byte (2 nibbles) to memory 

DO+2 % point to next char 

Le 50 % character P 

DATO=C B % write P 

DO+2 % point to next char 

LC 34 % character 4 

DATO=C B % write 4 

DO+2 % point to next char 

LC 39 % character 9 

DATO=C B % write 9 

DO+2 % point to next char 

LC 47 % character G 

DATO=C B % write G 


GOVLNG GPPushROLp % get pointers, push address in RO, 
% return to RPL 
ENDCODE 


, 


@" 


We can condense this significantly by not loading every character separately 
but all in one go: 
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GOSBVL PopASavptr 


DO=A 

DO+10 

LC 4739345048 
DATO=C 10 

GOVLNG GPPushROLp 
ENDCODE 


: d 





/e RPL pointers and get addr of 
% 1g 

% the addr of the string in RO 
% point to string prologue 

% skip prologue and prologue 

% load "HP49G" in C 

% write string 






% get pointers, push address RO, return % to RPL 
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3. Tests & loops 


Sometimes we need to test something and jump to a another point in the code 
(like an IF THEN ELSE if you like). The points to jump to are called labels. The 
assembler expects them after a "*" on a new line. The Saturn can perform many 
tests on its working registers. 


EXAMPLE 3.1 Comparing registers 


Let’s see if we can make a program that returns a TRUE flag if the value of the 
bint on the stack is #6FEh 


“yy 


#6FE 


CODE 

GOSBVL POP# % read a bint from the stack to A(A) 
SAVE % save RPL pointers 

LC OO6FE % this is the number to check 

?C=A A -> Equal % if they match jump to equal 
GOVLNG GPPushFLoop % if not get ptrs, push FALSE and loop 
* Equal 

GOVLNG GPPushTLoop % if match push TRUE 

ENDCODE 

@” 


Another useful thing to test for is the Carry. It is set when an overflow (or 
underflow) of a register occurs. So if you subtract something from 0 a carry will 
be set. This is extremely useful if you want to do something a number of times. 


EXAMPLE 3.2 Loops 


"OODE 
SAVE % we know this by now 
LC 0000A % load 10 inC 
*Labell % you can use any name for a label 
C-1A % subtract one from C 
% usually the A field is used as a 
% counter, although here we could have 
% used the B field 
GONC Labell % Go to Labell if there is no carry 
LOADRPL % MASD speak for GOVLNG GETPTRLOOP 
ENDCODE 
@" 
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This code will continue to subtract one from C until a carry is set. 
Question: How many times will this loop? 


No, it doesn’t loop 10 times. Let’s count the number of times the code passes 
Labell 








Zt Contents of C, after C-1A Carry 
1 No 
2 No 
3 No 
4 No 
5 No 
6 No 
7 No 
8 No 
9 No 
10 No 
11 FFFFF Yes 








It loops 11 times, so that is one more than what you start with. 


EXAMPLE 3.2A Masd syntax loop 

The masd syntax can be used to write this up a bit shorter. It compiles to exactly 
the same as example 3.2 Personally | do not use it, but that is because | 
learned | azz syntax first. See the masd documentation for the full masd syntax. 
“CODE 

SAVE % save RPL pointers 

LC 0000A 

{ C-1 A UPNC } % loop 11 times 

LOADRPL 

ENDCODE 


@” 
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EXAMPLE 3.3 Status bits 

The status bits are 16 bits that can be set and tested for easily, they are useful 
in keeping one bit data. You can use bits 0 thru 11, 12 thru 15 are used by the 
system, don’t set them if you do not know what you are doing! 


"CODE 

SAVE % save RPL 

CLRST % Clear status bits 0 thru 11 
ST=1 9 

?ST=0 9 -> Label2 % if bit 9 is not set jump to Label2 
LOADRPL % go back to RPL 

*Label2 

LOADRPL % go to RPL after jump 
ENDCODE 

@" 

EXAMPLE 3.4 Timer 


We will now discuss the built in timer, it decreases 8192 times per second and is 
8 nibbles wide. It is located at the address TIMER2. There is another timer called 
TIMER1, which decreases 16 times per second and is one nibble wide. We will 
use TIMER2 to show you an application of the P register. It takes a bint from the 
stack and waits that amount of ticks of the TIMER2. 


10000 ( put bint on the stack) 

CODE 

A=0 W % clear A because we need 8 nibbles 

GOSBVL POP# % read bint from stack 

SAVE % save pointers 

DO=(5) TIMER2 % point to TIMER2 

PS; % load P with 7 

C=DATO WP % read nibbles 0 true 7 

C-A WP % subtract the bint 

*Wait 

A=DATO WP % read timer 

?A>C WP -> Wait % wait until A is equal to C 
% or less than C if the moment has 
% passed 

P=0 % reset P to zero or else RPL will 
% crash 

LOADRPL % get pointers and return to RPL 

ENDCODE 

@” 


You can use this code with TEVAL but be sure to put a BINT on the stack. 
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4, Subroutines and the Return Stack 


We have seen in example 1.3. that there are some very useful subroutines 
already in ROM, but you can make your own. They are called with GOSUB which 
behaves the same as GOSBVL but you need to make your own routine 


EXAMPLE 4.1 Calling your subroutine 


“CODE 
SAVE % save RPL pointers 
GOSUB Delay % Call the subroutine Delay 

% put adress of next instruction 

% (GOSUB Delay) on return stack 
GOSUB Delay % do the delay routine again 

% and put the addr of LOADRPL in RSTK 
LOADRPL % return to RPL 
* Delay % Delay subroutine, it simply loops a 

% number of times before returning 
LC 03000 % loop #3001h times, can be any number 
*DelayLoop 
C-1A % subtract one 
GONC DelayLoop % goto DelayLoop until Carry is set 
RTN % jump to the adress in the return stack 
ENDCODE 
@” 


The return stack is a 8 level register that is a LIFO (last in first out) stack. It 
holds the address at which your code will continue after the subroutine. It can 
also be used as a place to save 5 nibbles. Be sure to remove them, otherwise the 
code may jump to that address! 

The instructions to manipulate the return stack are limited: 

RSTK=C puts the A field of the C register onto the returnstack 

C=RSTK reads the address on the return stack into C(A) and removes it from the 
return stack. 

Also all return commands pop one address from the return stack, and jump to it 


EXAMPLE 4.2 Using the return stack 
This code is not very useful but is shows how one can use the return stack to 


save some data. For example when you do not want to alter any of the other 
registers. 
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“CODE 


C=DAT1A % read the adress of the object on the 
% stack, if this is 0 the stack is empty 
CD1EX % exchange the registers D1 and C 


% so that C has the stack pointer and 
% D1 the object from the stack 
RSTK=C % save the stack pointer in RSTK because you 
% will need it to return to RPL at the end 
% of the code 


C=DAT1A % read the prologue, you could do other 
% things here 

C=RSTK % retrieve the stack pointer from the return 
% stack 

D1=C % reset D1 to the stack 

A=DAT0O A % recall next object in runstream 

DO+5 % set DO to "nextnext" object in runstream 

PC=(A) % set the program counter to the address A 
% is pointing to 

ENDCODE 

@” 


EXAMPLE 4.3 Data inside your code 


You can use a combination of a GOSUB and C=RSTK to get an address inside 
your code. This can be useful when you have some fixed data which you need 
in your code. 


“CODE 
SAVE % save rpl pointers 
GOSUB Data % jump to Data and save the address of the 


% next instruction (NIBHEX) in RSTK 
NIBHEX C2A20B10008454C4C4F40275F425C444 
% NIBHEX is a MASD directive that puts raw 
% hex in your code 
*Data 
C=RSTK % read the address of the data 
A=CA 
GOVLNG GPPushALp % push the data address to the stack 
ENDCODE 


@” 


We have pushed a string to the stack always be sure that you push good objects 
to the stack. A corrupt object may crash the calc. 
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5. Tempob 


When you want to make new objects you need to reserve an amount of 
memory. The easiest way to do this is to MAKE$. It will reserve the memory and 
make a string prologue and length. The address of the string will be in RO(A) and 
DO will point to the first character in the string. 

TempOb must always contain objects, if you put raw hex in it the next garbage 
collection will screw up your memory. MAKE$ takes care of this, if you use 
CREATETEMP you will have to do it yourself see chapter 8 for this. 

MAKE$ will however do a GARBAGE collection if there is not enough memory. 
Therefore you should not run any programs containing MAKE$ directly after 
compilation, instead store the code in a variable before running it. Also see 
chapter 8 for more information on this. 


EXAMPLE 5.1 Making a string 
We will make a string of 10 characters and make the first one a “A” 


“CODE 

SAVE % save pointers 

LC 0000A % number of characters 
GOSBVL MAKE$ % make the string 

Lead % character code for “A” 
DATO=C B % write the first character 


GOSBVL GPPushROLp % get pointers and push string to stack 
ENDCODE 
@” 


You will notice that the first character is an “A” but the rest of the string looks 
like garbage. This is because MAKE$ does reserve the memory but it will contain 
the leftovers from previous use. You will have to fill it in yourself. 
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EXAMPLE 5.2 Writing in ML 
Let’s fill the string with the ten numbers 0 to 9. We shall now use P as a counter, 
it is only one nibble wide so we can use it only for loops that loop 16 times or 


less 

“CODE 

SAVE % 
LC 0000A % 
GOSBVL MAKE$ % 
LC 30 % 
P=6 % 
*Write 

DATO=C B % 
C+1B % 
D0+2 % 
P+1 % 
GONC Write % 


GOSBVL GPPushROLp % 
ENDCODE 
@” 


It is important that P is reset to zero, because returning to RPL requires it. 


save pointers 

number of characters 

make the string 

character “0” 

16 minus the number of loops 


write the character 

next character 

point to next character 

increase until P= zero again 

loop 10 times 

get pointers and push string to stack 
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EXAMPLE 5.3 Shrinking the string 

Sometimes you do not know how big an object will be when it is finished, so you 
need to reserve sufficient memory and free the remainder when you are finished. 
We can use a routine called Shrink$ that does just that. In the following code we 
do know how big the object will be but that is beside the point. We will put the 
values of B(A) and D(A) in a list and push it to the stack. 


“CODE 

SAVE 

LC 01000 % reserve 1000 bytes 

GOSBVL MAKE$ 

LC 02A74 % DOLIST prologue 

DATO=C A % write it 

DO+5 % point to next addr 

LC 02971 % DOBINT prologue 

DATO=C A % write it 

DO+5 % and point to the next addr again 

C=BA 

DATO=C A % write value of B(A) 

DO+5 

LC 02911 % do all this again for D(A) 

DATO=CA 

DO+5 

C=DA 

DATO=C A 

DO+5 

LC 03126 % load SEMI 

DATO=C A % and write it to terminate the list 

DO+5 

GOSBVL Shrink$ % Shrink$ will shrink the string to the 
% current DO with the addr of the strin 
% prologue in RO 

A=RO0 A % RO is the string prologue 

A+10A % the list prologue is 10 nibbles down 

GOVLNG GPPushALp % pust it to the stack 

ENDCODE 

@” 
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6. The Screen 


Because ML is so fast it is very useful for displaying graphics on the screen. We 
will start with writing something to the screen. 


EXAMPLE 6.1 The Screen 


Let’s see if we can put some pixels on the screen, don’t be afraid it only looks 


like a crash! 


GOSBVL "DO->Row1" 


D1=A 
DO=00000 
LC(5) 34*56 


GOSBVL MOVEDOWN 
C=0A 

*Wait 

C+1A 

GONC Wait 
LOADRPL 


% this sets DO to the first 

% nibble of the screen buffer 

% A also contains the address 

% point DO to an address in mem 
% load 5 nibbles of C with 34*56 
% 34 nibbles per line 56 lines 

% copy C nibbles from DO to D1 
% make a little loop to allow 

% some time for viewing the text 


% return to RPL 


Pal 


EXAMPLE 6.2 Writing to the Screen 


While writing nibbles to the screen can be entertaining it may be more useful to 
write readable text. 


"CODE 

SAVE 

GOSBVL "D0->Row1" % point DO to screen 

GOSUB Data 

NIBHEX 8454C4C4F40275F425C444 

*Data 

C=RSTK % remember this from EXAMPLE 4.3? 

D1=C % point to characters 

LC 00005 

B=CA % B is the offset of the text in nibbles 

LC 00022 

D=C A % D is the width of the screen 
% usually it is 34 (#22h) 

LC 0000B % C is the number of characters 

GOSBVL "$5x7" % display the text in the screen 

C=0A % make that loop again 

*Wait 

C+1A 

GONC Wait 

LOADRPL % return to RPL 

ENDCODE 


And there we have the program you learn in every language! 


EXAMPLE 6.3 DISPADDR 

There is a very handy address called DISPADDR at #00120h you can write an 
address at this position and the system will start displaying the data at that 
address. DISPADDR is * WRITE* only 

So we can rewrite example 6.1 as 


"CODE 

SAVE 

DO= 00120 % DISPADDR 

A=0A % the address of the new screen 
DATO=AA 

LOADRPL % return to RPL 


Z2 


You noticed that there is no wait loop, this is because the DISPADDR pointer is 
not updated after the code is finished. To update the screen you could generate 
an error or reset the original pointer. 


EXAMPLE 6.4 Greyscales [ADVANCED] 


Greyscales are basically very simple. Since the pixels on the screen have only 
two states (on/off) you need to turn a pixel on and off really quick to get a grey 
pixel. The 49 has a grey grob type, which we shall not use. It is more 
instructional to use the old method of two 131*64 grobs, one beneath the other 
in a single 131*128 grob. This is also the format used by most PC based 
conversion programs. (| think XNView is very good). It means that with two 
grobs you can have 4 colours. The “heaviest” grob is the top one 


First we need to create a greyscale grob. We do this in UserRPL. 

<< 

#131d #128d BLANK {#0d #0d} #131d #32d BLANK NEG REPL {#0d #64d} 
#131d #16d BLANK NEG REPL {#0d #96d} #131d #16d BLANK NEG REPL 

>> 

The code will take the resulting grob as an argument on level 1 on the stack 
MAKE SURE there is a 131*128 grob on the stack or it may crash 


“CODE 
ST=0 15 % this turns off some interrupts 

% see below for further explanation 
GOSBVL =PopASavptr % get the address of the grob 


A+20A % point to grob body of heaviest grob 
B=AA % save addr in B 

GOSBVL "D0O->Row1" % get the addr of the current screen 
RO=A A % save it in RO 

LC(5) 64*34 % 64 lines and 34 nibbles per line 
C+BA % Add to addr of first grob so that 
A=CA % A has the addr of grob2 


DO= 00100 % 
C=DATO X % 


#00100h is BITOFFSET you can move the 
screen pixel by pixel by altering it 


o~ Oo 


RSTK=C % save current bitoffset in RSTK 

?ABIT=0 0 -> EVEN % if addr of grob is even no need to 
% shift 

Lt % shift 4 bits left (-4=C) 

DATO=C 1 % write new bitoffset 

DO= 00125 % LINENIBS contains the number of 
% nibbles per line 


LC FFF x 
DATO=C X x 


it has to be decreased because of the 
new bitoffset 


o~ Oo 
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*EVEN 
DO= 00120 
D1l= 00128 


LC. .3F 
DAT1=C B 


*MAI : 





GOSUB PAINT 
GOSUB PAINT 
ABEX A 


GOSBVL OnKeyDown? 


GONC MAIN 
ST=1 15 
A=ROA 
DATO=A A 
Lea? 
DAT1=C B 
D1-3 





LOADRPL 


*PAINT 


C=DAT1 


o~ Oo 


oO 


o~ oe 


o 


° 


oe 


oO 


% 


oO 


DISPADDR 


in LINECOUNT you can write the number 


of lines to be displayed 
64 lines including line 0 so #63d 








subroutine that displays grob in A 
switch grob1 and grob2 

display grob1 twice 

A has grob2 and B grob1 again 


OnKeyD wn? | sicellen a batt i the 





clear, hol 1g d lown 7 ON will halt the 
code until you release it, and the 
code will simply continue 


keep looping until ON key is pressed 


_ Allow the interrupts again 


Get the old display address 
it 


% res 


% 
% 


% 


oy OF OY OC 


oS 


} 


% display refres 





set the linecount back to 55 
00128 - 3 = 00125 LINENIBS 


set the LINENIBS to 0 

load the last two digits of DO with 
00 (00120 -> 00100 =BITOFFSET) 
get the old bitoffset 





return to RPL 


subroutine that waits until the 
h is at line 0 then 





% displays the grob inA 


% D1= LINECOUNT, when reading it, it 


% 
% 


has the current display line 
DO= DISPADDR 


read current display line 
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?C#0 B -> PAINT % until it is 0 

DATO=A A % write addr of grob 

*WAIT 

C=DAT1 % wait until line is no longer 0 
?C=0 B -> WAIT % or the screen may flicker 
RTN % return from subroutine 
ENDCODE 

@” 
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7. The Keyboard 


The keyboard can be read from the IN register, it must be run from a even 
address. This is why we use the romroutine “CINRTN” or “AINRTN” 

The IN register is 4 nibbles wide and the bits 0 to 8 are used for the keys, bit 11 
is set if ON is pressed. It more or less tells you which row the key is on. 

OUT is a three nibble wide register which is used to determine the “column” of 
the key. 


EXAMPLE 7.1 Waiting for a key 
This program waits for a key to be pressed and then returns the value of the IN 
register. 


‘CUE 

SAVE 

LC LFF % we need to set the out register to 
% nine ones 

OUT=C 

A=0A % clear 5 nibbles of A because the IN 
% register is only 4 nibbles wide 

*MAIN 

GOSBVL AINRTN % read the IN register 

?A=0 X -> MAIN % if no key then zero don't check for ON 

GOSBVL Flush % flush the key, or else it will be 
% executed after the code 

GOVLNG PUSH#ALOOP = % push the number to the stack 

ENDCODE 

@” 
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EXAMPLE 7.2 Reading the key code 


To read a key you need to set a mask in the out register, if you set one bit only 
keys from that column will result in an IN value. 

This program waits for a key press and return the IN and OUT registers to the 
stack. 


“CODE 

SAVE 

ST=0 15 % turn off interrupts 

C=0A % load C(A) with 1 

C+1A % this is shorter than LC 00001 

A=0A % clear A 

*MAIN 

P=0 % set P to zero, it may be three 
% after the test for IN 

C+CA % shift C left one bit 

?CBIT=0 9 -> RESET % OUT uses only 9 bits 

C=0A % so set bit 0 again 

C+1A 

TRESE! 

OUT=C % set the OUT mask 

GOSBVL AINRTN % read the IN register 

P=3 % test only 4 nibbles 

?A=0 WP -> MAIN % if not zero then key pressed from this 
% column 

P=0 % reset P to zero 

RO=A A % RO is the IN value 

R1=CA % and Rl has OUT 

ST=1 15 % allow interrupts again 

GOSBVL Flush % flush keys 

GOSBVL GETPTR % Get the RPL pointers 

GOSBVL PUSH2# % push RO and R1 to the stack 

GOVLNG LOOP % back to RPL 

ENDCODE 

@” 


EXAMPLE 7.3 Beeping in ML [ADVANCED] 

The out register can also be used to make beeps, the process is complicated but 
luckily we have the “makebeep” romroutine. It takes the pitch in Hz in D(A) and 
the length in msec in C(A). We shall now look at a piece of code that plays a 
hxsstring. The format of this string must be: 


27 


Hxsprologue, hxslength, pitch1, len1, pitch2, len2, ...... ,pitch#n, len#n. 


With pitch and len in three nibbles. 


EG HXS 0000C 8B1046601046, this would play an A and a C of 1,6 seconds 
To easily create these strings take a 


http://www.hpcalc.org/details.php?id=4698 


I've added a song already, you may have to remove the linefeeds in the 


hxsstring 


“yy. 


HXS OOOFC 


look at my NOKIA program 


C024B0000500C024B0C028618818614924B00005004924B0492861C02861C0286 
14924B00138610134B00005000134B0AB24B00005004924B0C42861C424B0000B 
00C424B00005004924B0AB2861AB28614924B0000500C424B0492861C02861C0 


24B00005004924B0C428610005008814B0EE14B0000500C424B0C02861 


CODE 


GOSBVL =PopASavptr 


D1=A 
D1+5 
C=DAT1 A 
C-11A 


GONC NULL 

LC 00203 

GOVLNG GPErrjmpC 
*NULL 

RSTK=C 


R4=A A 

?D#0 X -> NoPause 
GOSUB WAIT 
GOTO SKIP 
*NoPause 


% 


% 


& 


% 
% 
% 
% 


o~ Oo 


% 
% 
% 
% 
% 
% 
% 
% 
% 
% 
% 
% 


°o 


o~ Go Cig a oO ee 


fo) 


% 
% 
% 
% 


f=) 


°o 


o~ Oo 


get the addr of the hxs string 


point to length of hxsstring 

read length 

subtract 5 for length and 6 for 
predecrease 

if hxs smaller than 6 nibbles 

error out with “bad argument value” 


save length in RSTK 

A has addr of first pitch 

save in R4, make beep changes almost 
every register 

get addr of pitch 

point to it 

clear C, since makebeep uses 5 nibbles 
read pitch 

D(A) must have the pitch 

point to length of beep 

read it 

point to next pitch 


save it in R4 

if pitch is 0 then it is a pause 
do the wait subroutine 

and skip the beep 
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GOSBVL =makebeep 
*SKIP 
C=R5TK 
C-6A 

GONC END 
LOADRPL 
*END 
RSTK=C 
GOTO MAIN 





*WAIT 


ron (5) TIMER2 
= Ww 





A=DATO WwP 
nCeh. WP -> WLOOP 


ENDCODE 


F 


j @ ” 


% beep at pitch D(A) for C(A) msec 


% get the remaining length of the hxs 
% decrease by 6 nibbles per beep 

% and go to RPL if end is reached 

% return to RPL 


% save count in RSTK 
% and return do next beep 





% Wait subroutine, waits for sands Cie 


% 1/8 ‘ie 1/16 + 1/256 + 1/2048 = 0.19189 
% point to 8 nibble counter 

% clear A 

% get msec's 





% multiply by 8 


% add 1/8 msec’'s 
% C= 1/16 msec's 


% C= 1/256 msec’s 


% C= 1/2048 msec’s 


% 8 nibbles 
% read counter 
6 subtract number of ticks 


% read counter 

% loop until it is time 

% reset P 

4 and return from subroutine 


4 
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8. Garbage collections 


For certain programs you will need a lot of memory, then a garbage collection 
may be necessary. This code cannot be run from port 1 or 2 or TempOb, the 
garbage collection might move the code itself and the PC (program counter) 
would not point to the correct address. After compilation store it in a variable in 
your directory. 

Let’s see how it is done. 


EXAMPLE 8.1 Garbage collections 


“CODE 
SAVE % save rpl pointers 
LC OFO00 % 30 kB of room, you can change the 
% amount to see how the garbage 
% collections work 
R4=CA % save it in R4 
GOSBVL CREATETEMP % reserve the mem 
GONC MemOk % if no carry, it all worked 
% if carry was set there is to little 
% free mem 
GOSBVL GARBAGECOL % and we need to do a garbagecollection 
C=R4A % get the 30 kB again 
GOSBVL CREATETEMP % and try again to reserve the room 
GONC MemOk % if no carry goto MemOk 
GOVLNG GPMEMERR % if still not enough room, error out 
% with a “not enough memory” error 
*MemOk 
ADOEX 
DO=A % get the addr of tempob 
LC(5)DOCSTR % load the string prologue 
DATO=CA % write it at the start of tempob 
DO+5 % point to length of string 
C=R4A % size of tempob 
C-5A % subtract 5 nibbles for the prologue 
DATO=CA % write length 
GOVLNG GPPushALp % push it to the stack 
ENDCODE 
@” 


To make programs that can run from port 1 or 2 we need to use a little trick. 
We will do the garbage collection in SysRPL. It will move the code but the PC will 
be correct. 
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EXAMPLE 8.2 Garbage collections from TempOb 


It is important that, if your code needs arguments from the stack, you do not 


change the stack before you test the amount of memory. The code should be 


“restartable” after the GPMEMERR 


ERRSET 
CODE 
GOTO Start 


ENDCODE 
ERRTRAP 


~ GARBAGE 
CODE 
* Start 


SAVE 

LC OFO00 

R4=CA 

GOSBVL CREATETEMP 

GONC MemOk 

GOVLNG GPMEMERR 
*MemOk 

ADOEX 

DO=A 

LC(5)DOCSTR 

DATO=C A 

DO+5 

C=R4A 

C-5A 

DATO=C A 

GOVLNG GPPushALp 

ENDCODE 


@” 


( start the errortrapping structure) 


% goto the Start label in the next CODE 


% 


( if an error is found do the ) 
( garbagecollection and start the code) 


object 


( again ) 


( This is only done after an error) 


% 
% 


°o 


% 
% 


o~ oO 


% 


o 


% 
% 
% 
% 
% 
% 
% 
% 


o~ oO Ss Oo GY Oo Si 


Label to jump to from the first CODE 


object 


reserve 30 kB 
save for length 


error if not enough memory 


get the addr of tempob 
load the string prologue 


write it at the start of tempob 


point to length of string 
size of tempob 


subtract 5 nibbles for the prologue 


write length 


push the string to the stack 


If there is not enough memory after the garbage collection you will get the 
“insufficient memory” error 
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EXAMPLE 8.3 Reserving all memory [ADVANCED] 
There is a romroutine that reserves all the possible memory in a string, but leave 
room for pushing it to the stack. This is particularly useful when you do not know 
how much memory you will need. The romroutine is MAKERAMS. It will return 
the size of the string in D(A). You will have to make sure that you do not write 
anything outside of the string, so we will use D as a counter. We will now discuss 
a complicated example. It puts all the words in a string separately in a list. You 
cannot know how much memory you will need so we will reserve all the memory. 
We will also show how to leave the string on the stack in case you want to use 
the GARBAGE trick of example 8.2 


“word! word2 
word3 word4" 


GOSBVL MAKERAM$ 
A=R4A 

D1=A 

D-10 A 


GOC MEMERR 


LC(5)DOLIST 
DATO=C A 
DO+5 

DI+5 
C=DAT1A 
C-7A 


GOC NULL 
CSRB A 
B=CA 
D1+5 
*START 
LC 20 


*MAIN 
A=DAT1 B 


( sample string, you can also use) 
( the source itself) 


get the address but leave it on the 
stack and save it in R4 


reserve all memory 

get the string address 

point to string prologue 

D has the remaining nibbles in the 
TEMPOB string, decrease 10 nibbles 
for the DOLIST prologue and the SEMI 
if carry then not enough memory so 
error out 


write DOLIST prologue 

Skip it 

skip sample string prologue 

read size of string 

subtract 5 and 2 for predecrease 
it now has the number of nibbles 
minus two of the sample string 
if carry then null$ 

number of characters minus one 
use B as a character counter 
skip length 


use any character under #21h as a 
separation character 


read character 
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?C<A B -> BLACK 


D1+2 


B-1A 
GONC MAIN 
*NULL 
LC(5)SEMI 
DATO=C A 
DO+5 
GOSBVL Shrink$ 
A=R0A 

A+10A 








GOVLNG GPOverWrALp 


*MEMERR 


* BLACK 
D-10 A 





GOC iia 


nod 


A=0M 


Lea 


*CLOOP 
A=DAT1 B 


?A<C B -> WHITE 


D-2A 
GOC MEMERR 






if Ai is greater than 20 itis a 
aracter and therefore a word 
‘to make a new string in 


. if not it is a separation character 
> SO Skip it 

% decrease counter in B 

% if carry then end of string 





% load SEMI | 
% write it, to terminate the string 
% a th SEMI 







Zc f the TEMPOB string 
% point to the address of the list 

% overwrite the string on the stack 

% and push the list, return to RPL 


% jump here if there is to little mem 


% jump here if you find a new word 
% you need 5 nibbles for the prologue 
% and 5 for the size 

% memory error if carry 


> 





* get the address of the string in C 
% and Rl 
% string prologue 





% skip prologue and length because we 
% do not know the size of the word yet 
% clear nibbles 3 thru 14 of A 
y a counter, since we 
the B field of A for 








% smaller than that is a separation 
% character 





% read aes ri acter 





: Ory onenee chare 
% error out if not enough neriohe 
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DATO=A B 
A+1M 

Di+2 

DO+2 

B-1A 

GONC CLOOP 
B+1A 


*WHITE 





DO=C 
?B#0 A -> AGAIN 
GOTO NULL 


*AGAIN 
GOTO START 
ENDCODE 











% write the char ter 


% a d ; ¢ 


* § 
% end only ingle stri 
% then add one to B 


o~ Oo 





ng roids 





So 


when word ends jump here 
shift A(M) to A(A) 


So 


double to get size in nibbles 





get address of word prologue 


% | 
‘0 


% 


point to string length field 

write it 

and put DO back to addr after word 
if B=O then the sample string ends 
we need a GOTO here because 
GONC can only jump 256 nibbles 


oO oO oO 








» start a new word 
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9. Memory Banks 

The ports of the 49 are a very good place to keep your libraries and backup data. 
Sometimes you need to access one of the banks in a port or perhaps in ROM 
itself. You can do this with ACCESSBank0O, ACCESSBank1 to ACCESSBank15. 
They “open” the bank if P=0 and they “close” it if P=1. Other values for P have 
different operations but that goes to far here. 


EXAMPLE 9.1 Reading the serial number 
Let’s read the serial number of your 49, it is in BankO. 


“CODE 

SAVE 

LC OO00A % it is a string of 10 characters 

GOSBVL MAKE$ % sO make one! 

ADOEX 

D1=A % get the addr of the body of the 
% string in Dl and A 

P=0 

GOSBVL ACCESSBank0O % select the bank0O 

DO= 40130 % the ID is at this address 

LC 00014 % copy 20 nibbles 

GOSBVL MOVEDOWN 

rel % P=1 means return from that bank 

GOSBVL ACCESSBank0O 

GOVLNG GPPushROLp % push the string to the stack 

ENDCODE 

@” 


To work with libraries you should know how to access them in ML. There is a 
librarytable in memory which has the three nibble library 1D and the address of 
the library itself, as well as the address of the romroutine that you have to call to 
access the bank in which the library is located. The address of the lib points to 
the libid in the library itself and not to the prologue! 

The access routine should be called with a little trick you will see that in the 
example. 
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EXAMPLE 9.2 Reading a library title from a port [ADVANCED] 


This is an advanced example and you need to know a little about libraries to 


really understand it. 


GOSBVL POP# 
SAVE 

LC 101 

?A>C X -> LibOk 


LC 00203 

GOVLNG GPErrjmpC 
*LibOk 

DO= 8611D 
C=DATO X 

B=C X 

DO-13 


*Find 

DO+16 

B-1 X 

GONC END 

GOVLNG GPPushFLoop 


*END 

C=DATO X 
?A#C X -> Find 
DO+3 

A=DAT0O A 
R1=AA 

DO+5 
C=DATOA 
R2=C A 
GOSUB CallBank 
DO=A 

DO-2 


C=0A 
C=DATO B 
C+CA 
C+10A 


( library id of Emacs, you can change this) 


% 


get the id 


check if it is larger than 257 

test only last three digits because 
that is what you will be working with 
bad argument value error 


addr of libcount (number of libs) 
store it in B(X) as a counter 


+3 -16 skip lib count but 
“oredecrease” because you do a D0+16 


next 


point to next libid 


push False if end of libtable, so 


that lib is not there 


read lib id 


if not same then next one 


Skip lib id 

read addr of lib 

save in RO 

point to access routine 


save it in R2 
call the access routine 
point to libid in lib 


point to second title length field 
title itself will be in front of it 


clear C 
read title length in bytes 
title length in nibbles 


add 10 nibbles for prologue and 
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LC(5)DOCSTR 
DAT1=C A 
D1+5 





DATI=C A 
D1+5 
CDOEX 





=AA 
GOSBVL MOVEDOWN 
P=1 
GOSUB CallBank 
P=0 
A=R0 A 
GOSBVL GPPushA 
GOVING PushTLoop 


*CallBank 


C=R2A 
?C=0 A RTNYES 


ENDCODE 


@" 





rve the room 
_ if not enough room 
% error out 


% get addr of libid again 
% put it in DO 


% and point D1 to TEMPOB 
% string prologue 

% write it 

% Skip it 

% point to title length 


% length in nibbles 
% also store it in A 
% add 5 for length of stringlength 





% point to body of string 

% of title length field 
% subtract length 

% point DO to beginning of title 
% copy C nibbles 






% P=1 to return from the bank 
% call the access routine again 

% P could be 1 if library is in RAM 
% get the addr of TEMPOB 

% push it to the stack 

% push true and go to RPL 






ee 


xs 


% routine to access a bank 
efore calling it R2 should contain 









% library i is in y RAM. 
% point the programcounter to the 
% access routine 


as accessroutine from 


